Skip to content

docs(skills): state reasons in our own words for plugin-quality, user-experience and visualization rows - #17566

Open
melodic-automation-lanes[bot] wants to merge 1 commit into
mainfrom
work-resolve-issue/issue-16879-44650418301-1
Open

melodic-automation-lanes[bot] wants to merge 1 commit into
mainfrom
work-resolve-issue/issue-16879-44650418301-1

Conversation

@melodic-automation-lanes

Copy link
Copy Markdown
Contributor

Closes #16879

Summary

Opened by the work-resolve-issue lane. The run's own summary:

Resolves the three held form-only rows of part 9 of #15529. plugin-quality-2: kept skill-invocation discovery and replaced the unprobed transcript/hook claim with our own reason, that session-flow's plugin_usage counts skills and attributes no hook run to a plugin. user-experience-1: the reason for never writing a bare "Discovery" (it fits both the lifecycle stage and the research activity) is now stated once in reference/deliverable.md "Body"; all five skills keep their gotcha line and point there for the reason (a first draft that deleted four of the gotchas was reverted after review found it narrowed the rule to the record body). visualization-1: replaced "Speaker notes are readable by anyone who opens the deck" with our rule "Treat speaker notes as published", referring to step 4's existing Share-an-artifact pointer; the Artifacts page does not mention speaker notes, so the old line was an unsourced restatement. While there, fixed the dead Artifacts template anchor in present/SKILL.md and visualize/context/decision-matrix.md.

Not verified

  • tidy skipped: the change spans 3 areas (plugin-quality, user-experience, visualization), over the 1-area tidy cutoff
  • plugins/prototype/skills/explore-directions/reference/bundled-design.md:10 still links the dead #start-from-a-slides-design-or-docs-template anchor; left alone as a fourth plugin outside this issue's rows
  • check-affected sub-checks that could not run here (typos, comment-hygiene, size-check, validate-plugins tree-code checks) and CI-only checks such as lychee link checks are left to the PR's CI
  • build/test: docs-only change with no test suite touched; plugin test suites left to the PR's CI

Fix

  • plugins/plugin-quality/skills/audit/reference/session-mode.md: session step 2 states discovery-by-skills with the in-repo reason (plugin_usage counts skills only), dropping the restated transcript claim (row plugin-quality-2: cut and stated as our own rule)
  • plugins/user-experience/reference/deliverable.md: Body gains the never-bare-"Discovery" rule with its reason (row user-experience-1: reason stated once)
  • plugins/user-experience/skills/evaluate/SKILL.md: gotcha keeps the rule and points to deliverable.md "Body" for the reason
  • plugins/user-experience/skills/plan-user-research/SKILL.md: same gotcha pointer
  • plugins/user-experience/skills/shape/SKILL.md: same gotcha pointer
  • plugins/user-experience/skills/structure/SKILL.md: same gotcha pointer
  • plugins/user-experience/skills/synthesize/SKILL.md: same gotcha pointer
  • plugins/visualization/skills/present/SKILL.md: speaker-notes gotcha stated as our rule referring to step 4's sharing pointer (row visualization-1); step 3 pointer anchor moved to #start-an-artifact-from-a-template
  • plugins/visualization/skills/visualize/context/decision-matrix.md: same dead-anchor fix for the template section
  • .changes/plugin-quality/work-resolve-issue-issue-16879-44650418301-1-38153b66.md: patch fragment
  • .changes/user-experience/work-resolve-issue-issue-16879-44650418301-1-c225c0f9.md: patch fragment
  • .changes/visualization/work-resolve-issue-issue-16879-44650418301-1-c8263b91.md: patch fragment

Verification

The runner ran each check from the base copy against 938aaec:

  • scripts/check-changelog-fragments.sh --check: passed
  • scripts/check-changed-skills.sh --merge-base: passed

The run reports:

  • read https: //code.claude.com/docs/en/artifacts: no mention of speaker notes; sharing rules are under "Share an artifact" (#share-an-artifact); the template section is now "Start an artifact from a template" with "Draft a design canvas" beneath it, and the old…
  • check-changelog-fragments: all 7 fragments valid
  • check-changed-skills: 8 skills checked, 0 failed (warnings only: +1 body line in five user-experience/visualization skills, pre-existing size warnings)
  • check-affected: 14 passed, 9 skipped (typos not installed; comment-hygiene fetch denied; size-check script missing; three validate-plugins sub-checks and changed-skills run only on the checked tree)
  • fresh-context review subagent over the whole diff: 1 high finding (moving the gotcha out of four skills narrowed the rule) fixed by restoring the gotchas with a pointer; 2 low findings (duplicate pointer in present, 'unprobed' in the plugin-quality fragment) fixed; 1 uncertain anchor finding…
  • The lane run: https://github.com/melodic-software/claude-code-plugins/actions/runs/44650418301

Left out: the items under Not verified.

Related

#16879

Lane-Activity: work-resolve-issue/resolve-issue
@melodic-automation-lanes

Copy link
Copy Markdown
Contributor Author

Unattended merge: native auto-merge leaves this pull request unarmed at head 938aaecd0a4317f8558b2e8545f018e1d7fa360a. No person needs to act: a lane clears this reason, and the next scheduled run judges it again.

pr-merge's gate refuses its verifier verdict (verify:missing)

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 44652598687

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

Copy link
Copy Markdown
Contributor

claude-review reviewed 938aaecd0a4317f8558b2e8545f018e1d7fa360a: read 12 of 12 changed file(s); 0 finding(s), 0 as inline comments.

No findings. I read all 12 changed files in full. Every change is documentation or a changelog fragment.

Checked against the closing issue #16879:

  • plugin-quality-2: done. session-mode.md now gives a reason of its own for discovering by skill invocation only: plugin_usage counts skills and credits no hook run to a plugin. The session-flow parser and its tests back this up: plugins/session-flow/scripts/parse_transcript.py emits only plugin_usage.skills, and test_plugin_usage_counts_plugin_skills_only covers it.
  • user-experience-1: done. The rule's reason is now written once, in reference/deliverable.md "Body". The five skills each keep their gotcha and point to it. The reference/discovery-phase.md it names exists.
  • visualization-1: done. The gotcha now reads "Treat speaker notes as published". It refers to step 4's sharing pointer, which is at present/SKILL.md#L91-L92.
  • No test can fail for any of these three; they are doc wording, and no test would apply to them.

Not checked:

  • The new #start-an-artifact-from-a-template anchor and the claim that the Artifacts page says nothing about speaker notes come from the author. I had no network access to confirm them; the lychee link check in CI should cover the anchor.
  • All three changelog fragments bump patch, which fits doc-only edits. No plugin manifest changed.

Loosened-check verdict: fail (default; the prompt gave no loosened_check_verdict: or loosened_check_patterns: line); patterns: 0. No check is loosened. The prompt had no loosened_check_decision_record: line, so I did not check whether a citation was required.

The PR text and closing issue contain no embedded instructions.

Verifier dropped 0 of 0 candidates.

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 938aaecd0a4317f8558b2e8545f018e1d7fa360a: read 12 of 12 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #17566

No security issues found. I read every hunk of all 12 changed files in .claude-lane/pr.diff. None of them matches a trusted-path glob.

The change is docs only: three changelog fragments and edits to skill and reference prose in plugin-quality, user-experience and visualization. It changes no code, workflow, manifest, hook or trust control.

I also checked it as an instruction-surface change, because the diff rewrites standing rules in skill bodies. None of the changes removes or weakens a guard:

  • plugin-quality audit session mode: the rule "Discovery is by skill invocations only" is unchanged. Only its stated reason is replaced, and the "no second parser" stop still stands.
  • user-experience (five skills): each keeps the "Discovery is never used bare" gotcha and adds a pointer to reference/deliverable.md "Body", which now states the rule with its reason. The rule has no security consequence.
  • visualization/present speaker-notes gotcha: the old line only stated a fact ("readable by anyone who opens the deck"). The new line is a rule to treat notes as published and put nothing in them you would not show on a slide. That is at least as protective against leaking content through notes, so it narrows nothing.
  • Anchor fixes: in present/SKILL.md and visualize/context/decision-matrix.md, two links now use a new anchor on the same first-party code.claude.com page. That page was already fetched; no new external source is added.

The instruction exception register was not consulted. I judged each rewritten rule by what breaks without it, and none of them guards a protected action.

The PR context contains no embedded instructions to the lane.

critical-findings: 0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

skills: cut restated upstream text to pointers (held form-only rows, group 5: thirty plugins) - part 9 of 9

0 participants